14.4 Extracting source code

Creating pure source code files by extracting code from source blocks is referred to as “tangling”—a term adopted from the literate programming community. During “tangling” of code blocks their bodies are expanded using org-babel-expand-src-block which can expand both variable and “noweb” style references (see Noweb reference syntax).

Header arguments

:tangle no

The default. The code block is not included in the tangled output.

:tangle yes

Include the code block in the tangled output. The output file name is the name of the org file with the extension ‘.org’ replaced by the extension for the block language.

:tangle filename

Include the code block in the tangled output to file ‘filename’.

Functions

org-babel-tangle

Tangle the current file. Bound to C-c C-v t.

With prefix argument only tangle the current code block.

org-babel-tangle-file

Choose a file to tangle. Bound to C-c C-v f.

Hooks

org-babel-post-tangle-hook

This hook is run from within code files tangled by org-babel-tangle. Example applications could include post-processing, compilation or evaluation of tangled code files.

Jumping between code and Org

When tangling code from an Org-mode buffer to a source code file, you’ll frequently find yourself viewing the file of tangled source code (e.g., many debuggers point to lines of the source code file). It is useful to be able to navigate from the tangled source to the Org-mode buffer from which the code originated.

The org-babel-tangle-jump-to-org function provides this jumping from code to Org-mode functionality. Two header arguments are required for jumping to work, first the padline (padline) option must be set to true (the default setting), second the comments (comments) header argument must be set to links, which will insert comments into the source code buffer which point back to the original Org-mode file.